docs: clarify full node hardware requirements by yjkellyjoo · Pull Request #835 · ethersphere/bee-docs

yjkellyjoo · 2026-08-14T09:49:03Z

What does this PR resolve? 🚀

Corrects the documented full node hardware requirements and removes framing that made running a full node sound more demanding than it is.

Fixes the RAM figure: full nodes were documented as needing 8 GB; the actual ceiling is 500 MB, including while playing the redistribution game. The wrong figure appeared in three separate places.
Makes node-types.md the single source of truth for full node requirements. getting-started.md and faq.md now link to #full-node-specifications instead of carrying their own drifting copies.
Corrects the staking resource claim: the sampler was documented as having "high computational and memory requirements". It is CPU-bound, not memory-bound — 4 cores are sufficient.
Reframes the hardware bar across five pages: all three node types run on ordinary consumer hardware. The real differences for a full node are disk space, sustained bandwidth, and a funded blockchain connection.

Details 📝

The three copies of the full node spec had drifted apart (30 GB SSD vs. 20–30 GB NVMe), and the FAQ copy was the only one listing the on-chain funding requirements. Both lists are now merged into node-types.md under two groups — hardware, and blockchain/funding — so nothing was dropped in consolidation.

The :::warning above the full node spec list became an :::info placed below it. It previously primed readers to expect heavy requirements before showing them numbers that are anything but; it is guidance about staking, not a hazard.

Wording changes that followed from the corrected numbers:

staking.md — "resource intensive" → "CPU-intensive", with the 4-core figure and an explicit note that memory is not the constraint.
bee-api.md — /rchash benchmarks "your node's processor is fast enough" rather than "hardware is sufficient", since CPU is what it measures.
node-types.md — dropped "requires more system resources" and "without the overhead of running a full node".
Vague phrasing like "practically any modern computer" replaced with the concrete specs plus a reference point (laptops, desktops, or a Raspberry Pi with an attached SSD).

getting-started.md also gains a ## Requirements parent heading, with software/hardware/network demoted beneath it — the FAQ's #requirements anchor now points there. Some headings in faq.md were promoted from ##### to ###, which had been nested under a question rather than under a section.

No pages were added, renamed, or deleted.

Verification

npm run build:check passes: 0 broken internal links, 0 broken links in the built HTML (7,731 checked), 0 external 404s. The new #full-node-specifications, #requirements and #node-types-overview anchors were confirmed present in the build output, and all inbound links to them resolve.

The link checker also reports 16 stale external redirects, 7 unverifiable URLs and 6 llms.txt gaps. All are pre-existing on master and unrelated to these lines, so they are deliberately left for a separate link-maintenance PR.

Checklist ✅

Merged latest master and resolved conflicts
npm run build succeeds
Links checked (npm run check:links) where relevant
static/llms.txt updated if pages were added / renamed / deleted
Content follows CODING.md conventions (Swarm vs swarm, ..)
Self-reviewed the diff
Commits are signed off (git commit -s)

- have `node-types.md` as the single source of truth of requirements and others refer to that Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

- Document modest baseline requirements for all node modes - explain the added disk, bandwidth, blockchain, and CPU needs for full nodes and staking. Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

netlify · 2026-08-14T09:49:12Z

✅ Deploy Preview for test-twitter-preview-testing-3 ready!

Name	Link
🔨 Latest commit	`22b03ff`
🔍 Latest deploy log	https://app.netlify.com/projects/test-twitter-preview-testing-3/deploys/6a85b3d5c88f7d0008230525
😎 Deploy Preview	https://deploy-preview-835--test-twitter-preview-testing-3.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Cafe137 · 2026-08-14T10:08:51Z

+For both anchor parameters, use the first 4 hex digits from your node's overlay address (which you can find from the `/addresses` endpoint). 
+For depth, use the current storage depth of your node from the `/status` endpoint (`storageRadius` value):


Would it make sense to recommend swarm-cli utility rchash command here?

absolutely!
a3946ed added swarm-cli utility rchash alongside the API usage into tabs

Cafe137 · 2026-08-14T10:10:12Z

- **Internet**: High-speed and stable connection.
+- **RPC endpoint**: A connection to Gnosis Chain (see [setting the blockchain RPC endpoint](./configuration.md#setting-blockchain-rpc-endpoint)).
+- **xDAI**: Minimum 0.1 xDAI for Gnosis Chain gas fees.
+- **xBZZ**: 1 xBZZ for the initial chequebook deployment.


Wrong terminology.

1 xBZZ for the initial chequebook deposit.

Deployment only needs xDAI.

Also, funding the chequebook with xBZZ is optional.

17a7b09 dropped xBZZ from full node chequebook requirements

Cafe137 · 2026-08-14T10:24:59Z

-If you intend to participate in the redistribution game to earn storage incentives, you should test your setup using [the `/rchash` endpoint](./bee-api.md#rchash) in order to ensure that your hardware is sufficient. Participation in the redistribution game requires a process with high computational and memory requirements, along with significant bandwidth usage.
+:::info
+Staking raises the CPU demand but not the memory demand.
+Nodes selected for the redistribution game run the sampler process, which is CPU-bound and bandwidth-hungry; 4 cores are sufficient for it.


Is it really bandwidth hungry?

You're right, it's not, it's rather disk I/O heavy.
4e86b25 corrected it.

crtahlin · 2026-08-14T11:37:49Z

One caveat on the /rchash advice. Sampling time scales with how full the reserve is within radius: in my experience a node holding around 2M chunks (a practical lower bound) takes roughly half as long as one at around 4M (the upper bound). That is consistent with the code, since the sampler walks every chunk in radius. Crucially the operator cannot choose what they sample against — reserve occupancy at any given moment is a property of the network, not a setting — so an /rchash run only characterises the node against whatever the reserve happens to hold at that time. A comfortable result measured at 2M says little about the same node at 4M. Suggest the docs make clear that a single passing measurement is not a guarantee, and that operators should want real headroom rather than treat a marginal pass as sufficient.

crtahlin

Approving.

The RAM correction is right, and the consolidation works: after this change exactly one RAM figure remains anywhere in the docs (node-types.md), with no stale 8 GB left behind.
All three new anchors (#full-node-specifications, #node-types-overview, #requirements) resolve in the built preview.
awesome-lint is clean — the only warnings are the five that already exist on master.
The "4 cores" figure is well grounded: pkg/storer/sample.go runs max(4, runtime.NumCPU()) workers.

Two points already raised by @Cafe137 that I'd echo, both verified against Bee source:

Chequebook funding — --swap-initial-deposit defaults to 0 (cmd/bee/cmd/cmd.go) and pkg/settlement/swap/chequebook/init.go only requires xBZZ ≥ that deposit, so with defaults no xBZZ is needed; deployment costs xDAI gas only. Worth listing the xBZZ as an optional deposit.
Sampler bandwidth — pkg/storer/sample.go imports no networking or retrieval package; it iterates the local reserve and skips chunks that fail to load rather than fetching them. It is local disk I/O plus CPU, so "bandwidth-hungry" is worth dropping.

Neither blocks this PR. Separately, the /rchash advice has a gap that predates this change — see my comment above (#issuecomment-5292852749) on sampling time depending on reserve occupancy.

Description generated with help of AI.

xBZZ is not required to deploy a chequebook. Deploying the contract costs xDAI gas only, and the initial xBZZ deposit is optional: `swap-initial-deposit` defaults to `0`, and the chequebook init path only requires xBZZ to be greater than or equal to that deposit. The claim also contradicted two existing pages, which already document the deployment as xDAI-only: - fund-your-node.md lists "Chequebook Deployment" as < 0.001 xDAI and no xBZZ. - configuration.md describes the deposit as optional and defaulting to zero. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

The sampler was described as "bandwidth-hungry", and the /rchash troubleshooting advice named RAM as a main bottleneck. Neither holds: pkg/storer/sample.go imports no networking or retrieval package and reads chunks from the local chunk store, skipping any that fail to load. It never fetches from the network. What it does do is walk every chunk in radius, so the real constraints are processor speed and disk I/O. This is also why the specifications call for an SSD rather than an HDD. - node-types.md: describe staking as raising CPU demand and disk I/O. - bee-api.md: name disk and processor as the bottlenecks in the slow results warning, and drop the "consider more RAM" advice, which contradicted the corrected 500 MB figure. - staking.md: note that a slow disk can also cause a sampler timeout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

`swarm-cli utility rchash` needs no arguments: it reads the node's overlay address and committed depth and derives the anchor and depth parameters itself. The raw endpoint requires assembling both by hand, so the CLI is the better default. The API form stays fully documented in a second tab. Also corrects the depth guidance to use `committedDepth` rather than `storageRadius`, matching what swarm-cli passes. The two are equal unless `reserve-capacity-doubling` is set, in which case benchmarking at `storageRadius` measures a smaller sample than the node actually has to produce. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

Sampling time scales with how full the reserve is within radius, since the sampler walks every chunk in radius. Reserve occupancy follows network conditions and is not something an operator can choose, so a node measured against a half-full reserve can take roughly twice as long once the reserve approaches the default capacity of ~4M chunks. A marginal pass under the 360 second ceiling therefore says little about the same node later. Operators should look for real headroom rather than treating a single passing measurement as sufficient. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

yjkellyjoo · 2026-08-19T13:51:11Z

One caveat on the /rchash advice. Sampling time scales with how full the reserve is within radius: in my experience a node holding around 2M chunks (a practical lower bound) takes roughly half as long as one at around 4M (the upper bound). That is consistent with the code, since the sampler walks every chunk in radius. Crucially the operator cannot choose what they sample against — reserve occupancy at any given moment is a property of the network, not a setting — so an /rchash run only characterises the node against whatever the reserve happens to hold at that time. A comfortable result measured at 2M says little about the same node at 4M. Suggest the docs make clear that a single passing measurement is not a guarantee, and that operators should want real headroom rather than treat a marginal pass as sufficient.

@crtahlin Thanks for the comment.
22b03ff added a caution note that one rchash result is not a lasting guarantee

yjkellyjoo added 2 commits August 14, 2026 18:36

docs: Clarify Bee full node requirements and types

b8a9487

- have `node-types.md` as the single source of truth of requirements and others refer to that Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

docs: Clarify Bee node hardware requirements

2e6e0e0

- Document modest baseline requirements for all node modes - explain the added disk, bandwidth, blockchain, and CPU needs for full nodes and staking. Signed-off-by: Yejin Kelly Joo <yejinkellyjoo@gmail.com>

yjkellyjoo self-assigned this Aug 14, 2026

yjkellyjoo requested review from Cafe137, GasperX93 and crtahlin August 14, 2026 09:50

Cafe137 reviewed Aug 14, 2026

View reviewed changes

This was referenced Aug 14, 2026

Prevent users from staking on machines that cannot calculate proofs in time ethersphere/bee#4849

Open

rchash: report reserve size and estimate whether sampling finishes in time ethersphere/swarm-cli#783

Open

crtahlin approved these changes Aug 17, 2026

View reviewed changes

yjkellyjoo and others added 4 commits August 19, 2026 22:30

Cafe137 approved these changes Aug 19, 2026

View reviewed changes

Navigation Menu

Uh oh!

docs: clarify full node hardware requirements - #835

docs: clarify full node hardware requirements#835
yjkellyjoo wants to merge 6 commits into
masterfrom
fix/full-node-hw

yjkellyjoo commented Aug 14, 2026

Uh oh!

netlify Bot commented Aug 14, 2026 •

edited

Loading

Uh oh!

Cafe137 Aug 14, 2026

Uh oh!

yjkellyjoo Aug 19, 2026

Uh oh!

Cafe137 Aug 14, 2026

Uh oh!

yjkellyjoo Aug 19, 2026

Uh oh!

Cafe137 Aug 14, 2026

Uh oh!

yjkellyjoo Aug 19, 2026

Uh oh!

crtahlin commented Aug 14, 2026

Uh oh!

crtahlin left a comment

Uh oh!

yjkellyjoo commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		For both anchor parameters, use the first 4 hex digits from your node's overlay address (which you can find from the `/addresses` endpoint).
		For depth, use the current storage depth of your node from the `/status` endpoint (`storageRadius` value):

Uh oh!

Conversation

yjkellyjoo commented Aug 14, 2026

What does this PR resolve? 🚀

Details 📝

Verification

Checklist ✅

Uh oh!

netlify Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for test-twitter-preview-testing-3 ready!

Uh oh!

Cafe137 Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

yjkellyjoo Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

Cafe137 Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

yjkellyjoo Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

Cafe137 Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

yjkellyjoo Aug 19, 2026

Choose a reason for hiding this comment

Uh oh!

crtahlin commented Aug 14, 2026

Uh oh!

crtahlin left a comment

Choose a reason for hiding this comment

Uh oh!

yjkellyjoo commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify Bot commented Aug 14, 2026 •

edited

Loading